來介紹最近喜歡的 API 串接工具 TanStackQuery。

主要用來解決幾個問題：

• 管理 API 前端快取，包含自動重取過期的快取，以及更新資料後手動更新快取的功能。
• 避免同時執行重複的請求，會將多個重複請求整併後只請求一次並將回傳資料同步更新給所有請求。能夠在不同元件中共享同樣的回傳資料。

另外這組工具也有豐富的支援性：

• 有 React 版也有 Vue 版本，設定可以共用，並且格式一致。
• 有分頁跟無限捲動工具。
• 可以搭配 fetch 或 axios 等請求工具，且各個 query 可以用不同的 axios client，例如分成帶驗證 token 的 axios client 的跟沒有的。

安裝：

pnpm add -D  @tanstack/react-query

因為現在在 Next.js 上，要將 QueryClientProvider 包成 client component 後使用。

'use client';

import React from 'react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

// Create a client
const queryClient = new QueryClient();

export default function QueryProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    // Provide the client to your App
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  );
}

取資料的基本範例：

import { useQuery } from '@tanstack/react-query';

export default function Form() {
	 const { data, isLoading, error } = useQuery({
	    queryKey: ['pokemon', '1'],
	    queryFn: () =>
	      fetch('https://pokeapi.co/api/v2/pokemon/1').then(res => res.json()),
			cacheTime: 1000 * 60 * 60,
			refetchOnWindowFocus: false,
	  });

	return {
			// ...
	};
}

queryKey 是快取的參照鍵，無論是共用快取資料或是重整快取，都是比對這邊的內容，而且特別的是 TanStackQuery 的 key 可以用字串以外的資料類型做參照，像是物件也可以。

queryFn 用於取資料，不限定用什麼方式只要有回傳就好。

cacheTime 定義快取有效時長，沒設定的話就不會有快取功能。

refetchOnWindowFocus 預設每當回到視窗時就會自動重取一次資料，可以關掉。

除了 data 是取回來的資料外，也提供了很多內建的狀態，像是 isLoading 表示請求正在執行中，可能是第一次取資料或是正在更新資料。 error 就是 query 拋出的錯誤結果。

改資料的基本範例：

import { useMutation, useQueryClient } from '@tanstack/react-query';

export default function Form() {
	const queryClient = useQueryClient();
  const { mutate, isLoading, error } = useMutation({
    mutationFn: async (data: any) => {
      console.log('mutationFn', data);
    },
    onSuccess: () => {
      queryClient.invalidateQueries(['pokemon', '1']);
    },
  });
	
	return {
			// ...
	};
}

mutationFn 用於發出修改清求，用什麼方式都可以。

如果在請求成功後想要刷新某個 query 的暫存，就用 invalidateQueries 手動要求刷新資料。

如果 mutation 本身就有回傳資料，不想重取的話，也能直接設定暫存資料。

onSuccess: (data) => {
  queryClient.setQueryData(['pokemon', '1'], data);
}

除了上述基本功能外，TanStackQuery 還有非常非常多功能跟設定，官方文件平易近人，可以多看看。